---
title: RBAC
overview: Configuration affecting resource-based access control
location: https://istio.io/docs/reference/config/istio.rbac.v1alpha1.html
layout: protoc-gen-docs
number_of_entries: 6
---
<p>Istio RBAC (Role Based Access Control) defines ServiceRole and ServiceRoleBinding
objects.</p>

<p>A ServiceRole specification includes a list of rules (permissions). Each rule has
the following standard fields:
* services: a list of services.
* methods: HTTP methods or gRPC methods. Note that gRPC methods should be
  presented in the form of &ldquo;packageName.serviceName/methodName&rdquo;.
* paths: HTTP paths. It is ignored in gRPC case.</p>

<p>In addition to the standard fields, operators can use custom fields in the &ldquo;constraints&rdquo;
section. The name of a custom field must match one of the &ldquo;properties&rdquo; in the &ldquo;action&rdquo; part
of the &ldquo;authorization&rdquo; template (https://github.com/istio/istio/blob/master/mixer/template/authorization/template.proto).</p>

<p>For example, suppose we define an instance of the &ldquo;authorization&rdquo; template, named &ldquo;requestcontext&rdquo;.</p>

<pre><code>apiVersion: &quot;config.istio.io/v1alpha1&quot;
kind: authorization
metadata:
  name: requestcontext
  namespace: istio-system
spec:
  subject:
    user: request.auth.principal | &quot;&quot;
    groups: request.auth.principal | &quot;&quot;
    properties:
      service: source.service | &quot;&quot;
      namespace: source.namespace | &quot;&quot;
  action:
    namespace: destination.namespace | &quot;&quot;
    service: destination.service | &quot;&quot;
    method: request.method | &quot;&quot;
    path: request.path | &quot;&quot;
    properties:
      version: request.headers[&quot;version&quot;] | &quot;&quot;
</code></pre>

<p>Below is an example of ServiceRole object &ldquo;product-viewer&rdquo;, which has &ldquo;read&rdquo; (&ldquo;GET&rdquo; and &ldquo;HEAD&rdquo;)
access to &ldquo;products.svc.cluster.local&rdquo; service at versions &ldquo;v1&rdquo; and &ldquo;v2&rdquo;. &ldquo;path&rdquo; is not specified,
so it applies to any path in the service.</p>

<pre><code>apiVersion: &quot;config.istio.io/v1alpha1&quot;
kind: ServiceRole
metadata:
  name: products-viewer
  namespace: default
spec:
  rules:
  - services: [&quot;products.svc.cluster.local&quot;]
    methods: [&quot;GET&quot;, &quot;HEAD&quot;]
    constraints:
    - key: &quot;version&quot;
      value: [&quot;v1&quot;, &quot;v2&quot;]
</code></pre>

<p>A ServiceRoleBinding specification includes two parts:
* &ldquo;roleRef&rdquo; refers to a ServiceRole object in the same namespace.
* A list of &ldquo;subjects&rdquo; that are assigned the roles.</p>

<p>A subject is represented with a set of &ldquo;properties&rdquo;. The name of a property must match one of
the fields (&ldquo;user&rdquo; or &ldquo;groups&rdquo; or one of the &ldquo;properties&rdquo;) in the &ldquo;subject&rdquo; part of the &ldquo;authorization&rdquo;
template (https://github.com/istio/istio/blob/master/mixer/template/authorization/template.proto).</p>

<p>Below is an example of ServiceRoleBinding object &ldquo;test-binding-products&rdquo;, which binds two subjects
to ServiceRole &ldquo;product-viewer&rdquo;:
* User &ldquo;alice@yahoo.com&rdquo;
* &ldquo;reviews&rdquo; service in &ldquo;abc&rdquo; namespace.</p>

<pre><code>apiVersion: &quot;config.istio.io/v1alpha1&quot;
kind: ServiceRoleBinding
metadata:
  name: test-binding-products
  namespace: default
spec:
  subjects:
  - user: alice@yahoo.com
  - properties:
      service: &quot;reviews&quot;
      namespace: &quot;abc&quot;
  roleRef:
    kind: ServiceRole
    name: &quot;products-viewer&quot;
</code></pre>

<h2 id="AccessRule">AccessRule</h2>
<section>
<p>AccessRule defines a permission to access a list of services.</p>

<table class="message-fields">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr id="AccessRule.services">
<td><code>services</code></td>
<td><code>string[]</code></td>
<td>
<p>Required. A list of service names.
Exact match, prefix match, and suffix match are supported for service names.
For example, the service name &ldquo;bookstore.mtv.cluster.local&rdquo; matches
&ldquo;bookstore.mtv.cluster.local&rdquo; (exact match), or &ldquo;bookstore<em>&rdquo; (prefix match),
or &ldquo;</em>.mtv.cluster.local&rdquo; (suffix match).
If set to [&ldquo;*&rdquo;], it refers to all services in the namespace.</p>

</td>
</tr>
<tr id="AccessRule.paths">
<td><code>paths</code></td>
<td><code>string[]</code></td>
<td>
<p>Optional. A list of HTTP paths.
Exact match, prefix match, and suffix match are supported for paths.
For example, the path &ldquo;/books/review&rdquo; matches
&ldquo;/books/review&rdquo; (exact match), or &ldquo;/books/<em>&rdquo; (prefix match),
or &ldquo;</em>/review&rdquo; (suffix match).
If not specified, it applies to any path.</p>

</td>
</tr>
<tr id="AccessRule.methods">
<td><code>methods</code></td>
<td><code>string[]</code></td>
<td>
<p>Required. A list of HTTP methods (e.g., &ldquo;GET&rdquo;, &ldquo;POST&rdquo;) or gRPC methods.
gRPC methods must be presented as fully-qualified name in the form of
packageName.serviceName/methodName.
If set to [&ldquo;*&rdquo;], it applies to any method.</p>

</td>
</tr>
<tr id="AccessRule.constraints">
<td><code>constraints</code></td>
<td><code><a href="#AccessRule.Constraint">AccessRule.Constraint[]</a></code></td>
<td>
<p>Optional. Extra constraints in the ServiceRole specification.
The above ServiceRole examples shows an example of constraint &ldquo;version&rdquo;.</p>

</td>
</tr>
</tbody>
</table>
</section>
<h2 id="AccessRule.Constraint">AccessRule.Constraint</h2>
<section>
<p>Definition of a custom constraint. The key of a custom constraint must match
one of the &ldquo;properties&rdquo; in the &ldquo;action&rdquo; part of the &ldquo;authorization&rdquo; template
(https://github.com/istio/istio/blob/master/mixer/template/authorization/template.proto).</p>

<table class="message-fields">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr id="AccessRule.Constraint.key">
<td><code>key</code></td>
<td><code>string</code></td>
<td>
<p>Key of the constraint.</p>

</td>
</tr>
<tr id="AccessRule.Constraint.values">
<td><code>values</code></td>
<td><code>string[]</code></td>
<td>
<p>List of valid values for the constraint.
Exact match, prefix match, and suffix match are supported for constraint values.
For example, the value &ldquo;v1alpha2&rdquo; matches
&ldquo;v1alpha2&rdquo; (exact match), or &ldquo;v1<em>&rdquo; (prefix match),
or &ldquo;</em>alpha2&rdquo; (suffix match).</p>

</td>
</tr>
</tbody>
</table>
</section>
<h2 id="RoleRef">RoleRef</h2>
<section>
<p>RoleRef refers to a role object.</p>

<table class="message-fields">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr id="RoleRef.kind">
<td><code>kind</code></td>
<td><code>string</code></td>
<td>
<p>Required. The type of the role being referenced.
Currently, &ldquo;ServiceRole&rdquo; is the only supported value for &ldquo;kind&rdquo;.</p>

</td>
</tr>
<tr id="RoleRef.name">
<td><code>name</code></td>
<td><code>string</code></td>
<td>
<p>Required. The name of the ServiceRole object being referenced.
The ServiceRole object must be in the same namespace as the ServiceRoleBinding
object.</p>

</td>
</tr>
</tbody>
</table>
</section>
<h2 id="ServiceRole">ServiceRole</h2>
<section>
<p>ServiceRole specification contains a list of access rules (permissions).
This represent the &ldquo;Spec&rdquo; part of the ServiceRole object. The name and namespace
of the ServiceRole is specified in &ldquo;metadata&rdquo; section of the ServiceRole object.</p>

<table class="message-fields">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr id="ServiceRole.rules">
<td><code>rules</code></td>
<td><code><a href="#AccessRule">AccessRule[]</a></code></td>
<td>
<p>Required. The set of access rules (permissions) that the role has.</p>

</td>
</tr>
</tbody>
</table>
</section>
<h2 id="ServiceRoleBinding">ServiceRoleBinding</h2>
<section>
<p>ServiceRoleBinding assigns a ServiceRole to a list of subjects.
This represents the &ldquo;Spec&rdquo; part of the ServiceRoleBinding object. The name and namespace
of the ServiceRoleBinding is specified in &ldquo;metadata&rdquo; section of the ServiceRoleBinding
object.</p>

<table class="message-fields">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr id="ServiceRoleBinding.subjects">
<td><code>subjects</code></td>
<td><code><a href="#Subject">Subject[]</a></code></td>
<td>
<p>Required. List of subjects that are assigned the ServiceRole object.</p>

</td>
</tr>
<tr id="ServiceRoleBinding.roleRef">
<td><code>roleRef</code></td>
<td><code><a href="#RoleRef">RoleRef</a></code></td>
<td>
<p>Required. Reference to the ServiceRole object.</p>

</td>
</tr>
</tbody>
</table>
</section>
<h2 id="Subject">Subject</h2>
<section>
<p>Subject defines an identity or a group of identities. The identity is either a user or
a group or identified by a set of &ldquo;properties&rdquo;. The name of the &ldquo;properties&rdquo; must match
the &ldquo;properties&rdquo; in the &ldquo;subject&rdquo; part of the &ldquo;authorization&rdquo; template
(https://github.com/istio/istio/blob/master/mixer/template/authorization/template.proto).</p>

<table class="message-fields">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr id="Subject.user">
<td><code>user</code></td>
<td><code>string</code></td>
<td>
<p>Optional. The user name/ID that the subject represents.</p>

</td>
</tr>
<tr id="Subject.group">
<td><code>group</code></td>
<td><code>string</code></td>
<td>
<p>Optional. The group that the subject belongs to.</p>

</td>
</tr>
<tr id="Subject.properties">
<td><code>properties</code></td>
<td><code>map&lt;string,&nbsp;string&gt;</code></td>
<td>
<p>Optional. The set of properties that identify the subject.
In the above ServiceRoleBinding example, the second subject has two properties:
    service: &ldquo;reviews&rdquo;
    namespace: &ldquo;abc&rdquo;</p>

</td>
</tr>
</tbody>
</table>
</section>
